<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
	<title>SQLAlchemy 0.4 Documentation - Overview / Installation</title>
	
    <link rel="stylesheet" href="style.css"></link>
    <link rel="stylesheet" href="docs.css"></link>
    <link href="syntaxhighlight.css" rel="stylesheet" type="text/css"></link>
    <script src="scripts.js"></script>



</head>
<body>








<div id="topanchor"><a name="top">&nbsp;</a></div>


<h1>SQLAlchemy 0.4 Documentation</h1>

<div id="pagecontrol"><a href="index.html">Multiple Pages</a> | <a href="documentation.html">One Page</a></div>

<div class="versionheader">Version: 0.4.8   Last Updated: 10/12/08 13:33:19</div>







<A name=""></a>


    <div class="topnav">

    
    <div class="navbanner">
        <a href="index.html" class="totoc">Table of Contents</a>
        
    <div class="prevnext">


            
            Next: <a href="ormtutorial.html">Object Relational Tutorial</a>
    </div>

        <h2>Overview / Installation</h2>
    </div>

	
	
    <ul>
        
        <li><a style="" href="intro.html#overview_overview">Overview</a></li>

        
        <li><a style="" href="intro.html#overview_tutorials">Tutorials</a></li>

        
        <li><a style="" href="intro.html#overview_reference">Reference Documentation</a></li>

        
        <li><a style="" href="intro.html#overview_sqlalchemy">Installing SQLAlchemy</a></li>

	        <li>
                
    <ul>
        
        <li><a style="" href="intro.html#overview_sqlalchemy_dbms">Installing a Database API</a></li>

        
        <li><a style="" href="intro.html#overview_sqlalchemy_checking">Checking the Installed SQLAlchemy Version</a></li>

    </ul>

	        </li>
        
        <li><a style="" href="intro.html#overview_migration">0.3 to 0.4 Migration</a></li>

	        <li>
                
    <ul>
        
        <li><a style="" href="intro.html#overview_migration_imports">ORM Package is now sqlalchemy.orm</a></li>

        
        <li><a style="" href="intro.html#overview_migration_metadata">BoundMetaData is now MetaData</a></li>

        
        <li><a style="" href="intro.html#overview_migration_global">"Magic" Global MetaData removed</a></li>

        
        <li><a style="" href="intro.html#overview_migration_generative">Some existing select() methods become generative</a></li>

        
        <li><a style="" href="intro.html#overview_migration_collection">collection_class behavior is changed</a></li>

        
        <li><a style="" href="intro.html#overview_migration_bind">All "engine", "bind_to", "connectable" Keyword Arguments Changed to "bind"</a></li>

        
        <li><a style="" href="intro.html#overview_migration_type">All "type" Keyword Arguments Changed to "type_"</a></li>

        
        <li><a style="" href="intro.html#overview_migration_mapper">Mapper Extensions must return EXT_CONTINUE to continue execution to the next mapper</a></li>

    </ul>

	        </li>
    </ul>

	</div>











    
    <A name="overview"></a>
    
    <div class="sectionL1">

    
    



    
    <A name="overview_overview"></a>
    
    <div class="sectionL2">

    <h3>Overview</h3>
    
    

<p>The SQLAlchemy SQL Toolkit and Object Relational Mapper is a comprehensive set of tools for working with databases and Python.  It has several distinct areas of functionality which can be used individually or combined together.  Its major API components, all public-facing, are illustrated below:
</p>

    

    <div class="sliding_code">
        <pre>
           +-----------------------------------------------------------+
           |             Object Relational Mapper (ORM)                |
           |                <a href="ormtutorial.html">[tutorial]</a>    <a href="mappers.html">[docs]</a>                       |
           +-----------------------------------------------------------+
           +---------+ +------------------------------------+ +--------+
           |         | |       SQL Expression Language      | |        |
           |         | |        <a href="sqlexpression.html">[tutorial]</a>  <a href="sqlalchemy_sql_expression.html#docstrings_sqlalchemy.sql.expression">[docs]</a>          | |        |
           |         | +------------------------------------+ |        |
           |         +-----------------------+ +--------------+        |
           |        Dialect/Execution        | |    Schema Management  |
           |              <a href="dbengine.html">[docs]</a>             | |        <a href="metadata.html">[docs]</a>         |
           +---------------------------------+ +-----------------------+
           +----------------------+ +----------------------------------+
           |  Connection Pooling  | |              Types               |
           |        <a href="pooling.html">[docs]</a>        | |              <a href="types.html">[docs]</a>              |
           +----------------------+ +----------------------------------+
</pre>
    </div>
<p>Above, the two most significant front-facing portions of SQLAlchemy are the <strong>Object Relational Mapper</strong> and the <strong>SQL Expression Language</strong>.  These are two separate toolkits, one building off the other.  SQL Expressions can be used independently of the ORM.  When using the ORM, the SQL Expression language is used to establish object-relational configurations as well as in querying.
</p>



            <a href="#top" class="totoc">back to section top</a>
    </div>



    
    <A name="overview_tutorials"></a>
    
    <div class="sectionL2">

    <h3>Tutorials</h3>
    
    

<ul>
 <li>
     <a href="ormtutorial.html">Object Relational Tutorial</a> - This describes the richest feature of SQLAlchemy, its object relational mapper.  If you want to work with higher-level SQL which is constructed automatically for you, as well as management of Python objects, proceed to this tutorial.
 </li>

 <li>
     <a href="sqlexpression.html">SQL Expression Tutorial</a> - The core of SQLAlchemy is its SQL expression language.  The SQL Expression Language is a toolkit all its own, independent of the ORM package, which can be used to construct manipulable SQL expressions which can be programmatically constructed, modified, and executed, returning cursor-like result sets.  It's a lot more lightweight than the ORM and is appropriate for higher scaling SQL operations.  It's also heavily present within the ORM's public facing API, so advanced ORM users will want to master this language as well.
 </li>
</ul>



            <a href="#top" class="totoc">back to section top</a>
    </div>



    
    <A name="overview_reference"></a>
    
    <div class="sectionL2">

    <h3>Reference Documentation</h3>
    
    

<ul>
 <li>
     <a href="mappers.html">Datamapping</a> - A comprehensive walkthrough of major ORM patterns and techniques.
 </li>

 <li>
     <a href="session.html">Session</a> - A detailed description of SQLAlchemy's Session object
 </li>

 <li>
     <a href="dbengine.html">Engines</a> - Describes SQLAlchemy's database-connection facilities, including connection documentation and working with connections and transactions. 
 </li>

 <li>
     <a href="pooling.html">Connection Pools</a> - Further detail about SQLAlchemy's connection pool library.
 </li>

 <li>
     <a href="metadata.html">Metadata</a> - All about schema management using <code>MetaData</code> and <code>Table</code> objects; reading database schemas into your application, creating and dropping tables, constraints, defaults, sequences, indexes.
 </li>

 <li>
     <a href="types.html">Types</a> - Datatypes included with SQLAlchemy, their functions, as well as how to create your own types.
 </li>

 <li>
     <a href="plugins.html">Plugins</a> - Included addons for SQLAlchemy
 </li>
</ul>



            <a href="#top" class="totoc">back to section top</a>
    </div>



    
    <A name="overview_sqlalchemy"></a>
    
    <div class="sectionL2">

    <h3>Installing SQLAlchemy</h3>
    
    

<p>Installing SQLAlchemy from scratch is most easily achieved with <a href='http://peak.telecommunity.com/DevCenter/setuptools'>setuptools</a>.  (<a href='http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions'>setuptools installation</a>). Just run this from the command-line:
</p>
<pre><code># easy_install SQLAlchemy
</code></pre><p>This command will download the latest version of SQLAlchemy from the <a href='http://pypi.python.org/pypi/SQLAlchemy'>Python Cheese Shop</a> and install it to your system.
</p>
<p>Otherwise, you can install from the distribution using the <code>setup.py</code> script:
</p>
<pre><code># python setup.py install
</code></pre>

    
    <A name="overview_sqlalchemy_dbms"></a>
    
    <div class="sectionL3">

    <h3>Installing a Database API</h3>
    
    

<p>SQLAlchemy is designed to operate with a <a href='http://www.python.org/doc/peps/pep-0249/'>DB-API</a> implementation built for a particular database, and includes support for the most popular databases:
</p>
<ul>
 <li>
     Postgres:  <a href='http://www.initd.org/tracker/psycopg/wiki/PsycopgTwo'>psycopg2</a>
 </li>

 <li>
     SQLite:  <a href='http://initd.org/tracker/pysqlite'>pysqlite</a>, <a href='http://docs.python.org/lib/module-sqlite3.html'>sqlite3</a> (included with Python 2.5 or greater)
 </li>

 <li>
     MySQL:   <a href='http://sourceforge.net/projects/mysql-python'>MySQLdb</a>
 </li>

 <li>
     Oracle:  <a href='http://www.cxtools.net/default.aspx?nav=home'>cx_Oracle</a>
 </li>

 <li>
     MS-SQL:  <a href='http://pyodbc.sourceforge.net/'>pyodbc</a> (recommended), <a href='http://adodbapi.sourceforge.net/'>adodbapi</a>  or <a href='http://pymssql.sourceforge.net/'>pymssql</a>
 </li>

 <li>
     Firebird:  <a href='http://kinterbasdb.sourceforge.net/'>kinterbasdb</a>
 </li>

 <li>
     Informix:  <a href='http://informixdb.sourceforge.net/'>informixdb</a>
 </li>
</ul>



            <a href="#top" class="totoc">back to section top</a>
    </div>



    
    <A name="overview_sqlalchemy_checking"></a>
    
    <div class="sectionL3">

    <h3>Checking the Installed SQLAlchemy Version</h3>
    
    

<p>This documentation covers SQLAlchemy version 0.4.  If you're working on a system that already has SQLAlchemy installed, check the version from your Python prompt like this:
</p>

    

    <div class="sliding_code">
        <pre>
<span class="python_literal">&gt;&gt;&gt; </span><span class="python_keyword">import </span><span class="python_name">sqlalchemy</span><span class="python_operator">
</span><span class="python_literal">&gt;&gt;&gt; </span><span class="python_name">sqlalchemy</span><span class="python_operator">.</span><span class="python_name">__version__ </span><span class="python_operator">
</span><span class="python_number">0.4.0</span><span class="python_operator">
</span></pre>
    </div>



            <a href="#top" class="totoc">back to section top</a>
    </div>




    </div>



    
    <A name="overview_migration"></a>
    
    <div class="sectionL2">

    <h3>0.3 to 0.4 Migration</h3>
    
    

<p>From version 0.3 to version 0.4 of SQLAlchemy, some conventions have changed.  Most of these conventions are available in the most recent releases of the 0.3 series starting with version 0.3.9, so that you can make a 0.3 application compatible with 0.4 in most cases.
</p>
<p>This section will detail only those things that have changed in a backwards-incompatible manner.  For a full overview of everything that's new and changed, see <a href='http://www.sqlalchemy.org/trac/wiki/WhatsNewIn04'>WhatsNewIn04</a>.
</p>


    
    <A name="overview_migration_imports"></a>
    
    <div class="sectionL3">

    <h3>ORM Package is now sqlalchemy.orm</h3>
    
    

<p>All symbols related to the SQLAlchemy Object Relational Mapper, i.e. names like <code>mapper()</code>, <code>relation()</code>, <code>backref()</code>, <code>create_session()</code> <code>synonym()</code>, <code>eagerload()</code>, etc. are now only in the <code>sqlalchemy.orm</code> package, and <strong>not</strong> in <code>sqlalchemy</code>.  So if you were previously importing everything on an asterisk:
</p>

    

    <div class="sliding_code">
        <pre>
<span class="python_keyword">from </span><span class="python_name">sqlalchemy </span><span class="python_keyword">import </span><span class="python_operator">*
</span></pre>
    </div>
<p>You should now import separately from orm:
</p>

    

    <div class="sliding_code">
        <pre>
<span class="python_keyword">from </span><span class="python_name">sqlalchemy </span><span class="python_keyword">import </span><span class="python_operator">*
</span><span class="python_keyword">from </span><span class="python_name">sqlalchemy</span><span class="python_operator">.</span><span class="python_name">orm </span><span class="python_keyword">import </span><span class="python_operator">*
</span></pre>
    </div>
<p>Or more commonly, just pull in the names you'll need:
</p>

    

    <div class="sliding_code">
        <pre>
<span class="python_keyword">from </span><span class="python_name">sqlalchemy </span><span class="python_keyword">import </span><span class="python_name">create_engine</span><span class="python_operator">, </span><span class="python_name">MetaData</span><span class="python_operator">, </span><span class="python_name">Table</span><span class="python_operator">, </span><span class="python_name">Column</span><span class="python_operator">, </span><span class="python_name">types</span><span class="python_operator">
</span><span class="python_keyword">from </span><span class="python_name">sqlalchemy</span><span class="python_operator">.</span><span class="python_name">orm </span><span class="python_keyword">import </span><span class="python_name">mapper</span><span class="python_operator">, </span><span class="python_name">relation</span><span class="python_operator">, </span><span class="python_name">backref</span><span class="python_operator">, </span><span class="python_name">create_session</span><span class="python_operator">
</span></pre>
    </div>



            <a href="#top" class="totoc">back to section top</a>
    </div>



    
    <A name="overview_migration_metadata"></a>
    
    <div class="sectionL3">

    <h3>BoundMetaData is now MetaData</h3>
    
    

<p>The <code>BoundMetaData</code> name is removed.  Now, you just use <code>MetaData</code>.  Additionally, the <code>engine</code> parameter/attribute is now called <code>bind</code>, and <code>connect()</code> is deprecated:
</p>

    

    <div class="sliding_code">
        <pre>
<span class="python_comment"># plain metadata
</span><span class="python_name">meta </span><span class="python_operator">= </span><span class="python_name">MetaData</span><span class="python_enclosure">()</span><span class="python_operator">
</span>
<span class="python_comment"># metadata bound to an engine
</span><span class="python_name">meta </span><span class="python_operator">= </span><span class="python_name">MetaData</span><span class="python_enclosure">(</span><span class="python_name">engine</span><span class="python_enclosure">)</span><span class="python_operator">
</span>
<span class="python_comment"># bind metadata to an engine later
</span><span class="python_name">meta</span><span class="python_operator">.</span><span class="python_name">bind </span><span class="python_operator">= </span><span class="python_name">engine</span><span class="python_operator">
</span></pre>
    </div>
<p>Additionally, <code>DynamicMetaData</code> is now known as <code>ThreadLocalMetaData</code>.
</p>



            <a href="#top" class="totoc">back to section top</a>
    </div>



    
    <A name="overview_migration_global"></a>
    
    <div class="sectionL3">

    <h3>"Magic" Global MetaData removed</h3>
    
    

<p>There was an old way to specify <code>Table</code> objects using an implicit, global <code>MetaData</code> object.  To do this you'd omit the second positional argument, and specify <code>Table('tablename', Column(...))</code>.  This no longer exists in 0.4 and the second <code>MetaData</code> positional argument is required, i.e. <code>Table('tablename', meta, Column(...))</code>.
</p>



            <a href="#top" class="totoc">back to section top</a>
    </div>



    
    <A name="overview_migration_generative"></a>
    
    <div class="sectionL3">

    <h3>Some existing select() methods become generative</h3>
    
    

<p>The methods <code>correlate()</code>, <code>order_by()</code>, and <code>group_by()</code> on the <code>select()</code> construct now return a <strong>new</strong> select object, and do not change the original one.  Additionally, the generative methods <code>where()</code>, <code>column()</code>, <code>distinct()</code>, and several others have been added:
</p>

    

    <div class="sliding_code">
        <pre>
<span class="python_name">s </span><span class="python_operator">= </span><span class="python_name">table</span><span class="python_operator">.</span><span class="python_name">select</span><span class="python_enclosure">()</span><span class="python_operator">.</span><span class="python_name">order_by</span><span class="python_enclosure">(</span><span class="python_name">table</span><span class="python_operator">.</span><span class="python_name">c</span><span class="python_operator">.</span><span class="python_name">id</span><span class="python_enclosure">)</span><span class="python_operator">.</span><span class="python_name">where</span><span class="python_enclosure">(</span><span class="python_name">table</span><span class="python_operator">.</span><span class="python_name">c</span><span class="python_operator">.</span><span class="python_name">x</span><span class="python_operator">==</span><span class="python_number">7</span><span class="python_enclosure">)</span><span class="python_operator">
</span><span class="python_name">result </span><span class="python_operator">= </span><span class="python_name">engine</span><span class="python_operator">.</span><span class="python_name">execute</span><span class="python_enclosure">(</span><span class="python_name">s</span><span class="python_enclosure">)</span><span class="python_operator">
</span></pre>
    </div>



            <a href="#top" class="totoc">back to section top</a>
    </div>



    
    <A name="overview_migration_collection"></a>
    
    <div class="sectionL3">

    <h3>collection_class behavior is changed</h3>
    
    

<p>If you've been using the <code>collection_class</code> option on <code>mapper()</code>, the requirements for instrumented collections have changed.  For an overview, see <a href="mappers.html#advdatamapping_relation_collections">Alternate Collection Implementations</a>.
</p>



            <a href="#top" class="totoc">back to section top</a>
    </div>



    
    <A name="overview_migration_bind"></a>
    
    <div class="sectionL3">

    <h3>All "engine", "bind_to", "connectable" Keyword Arguments Changed to "bind"</h3>
    
    

<p>This is for create/drop statements, sessions, SQL constructs, metadatas:
</p>

    

    <div class="sliding_code">
        <pre>
<span class="python_name">myengine </span><span class="python_operator">= </span><span class="python_name">create_engine</span><span class="python_enclosure">(</span><span class="python_literal">'sqlite://'</span><span class="python_enclosure">)</span><span class="python_operator">
</span>
<span class="python_name">meta </span><span class="python_operator">= </span><span class="python_name">MetaData</span><span class="python_enclosure">(</span><span class="python_name">myengine</span><span class="python_enclosure">)</span><span class="python_operator">
</span>
<span class="python_name">meta2 </span><span class="python_operator">= </span><span class="python_name">MetaData</span><span class="python_enclosure">()</span><span class="python_operator">
</span><span class="python_name">meta2</span><span class="python_operator">.</span><span class="python_name">bind </span><span class="python_operator">= </span><span class="python_name">myengine</span><span class="python_operator">
</span>
<span class="python_name">session </span><span class="python_operator">= </span><span class="python_name">create_session</span><span class="python_enclosure">(</span><span class="python_name">bind</span><span class="python_operator">=</span><span class="python_name">myengine</span><span class="python_enclosure">)</span><span class="python_operator">
</span>
<span class="python_name">statement </span><span class="python_operator">= </span><span class="python_name">select</span><span class="python_enclosure">([</span><span class="python_name">table</span><span class="python_enclosure">]</span><span class="python_operator">, </span><span class="python_name">bind</span><span class="python_operator">=</span><span class="python_name">myengine</span><span class="python_enclosure">)</span><span class="python_operator">
</span>
<span class="python_name">meta</span><span class="python_operator">.</span><span class="python_name">create_all</span><span class="python_enclosure">(</span><span class="python_name">bind</span><span class="python_operator">=</span><span class="python_name">myengine</span><span class="python_enclosure">)</span><span class="python_operator">
</span></pre>
    </div>



            <a href="#top" class="totoc">back to section top</a>
    </div>



    
    <A name="overview_migration_type"></a>
    
    <div class="sectionL3">

    <h3>All "type" Keyword Arguments Changed to "type_"</h3>
    
    

<p>This mostly applies to SQL constructs where you pass a type in:
</p>

    

    <div class="sliding_code">
        <pre>
<span class="python_name">s </span><span class="python_operator">= </span><span class="python_name">select</span><span class="python_enclosure">([</span><span class="python_name">mytable</span><span class="python_enclosure">]</span><span class="python_operator">, </span><span class="python_name">mytable</span><span class="python_operator">.</span><span class="python_name">c</span><span class="python_operator">.</span><span class="python_name">x</span><span class="python_operator">=</span><span class="python_name">bindparam</span><span class="python_enclosure">(</span><span class="python_name">y</span><span class="python_operator">, </span><span class="python_name">type_</span><span class="python_operator">=</span><span class="python_name">DateTime</span><span class="python_enclosure">))</span><span class="python_operator">
</span>
<span class="python_name">func</span><span class="python_operator">.</span><span class="python_name">now</span><span class="python_enclosure">(</span><span class="python_name">type_</span><span class="python_operator">=</span><span class="python_name">DateTime</span><span class="python_enclosure">)</span><span class="python_operator">
</span></pre>
    </div>



            <a href="#top" class="totoc">back to section top</a>
    </div>



    
    <A name="overview_migration_mapper"></a>
    
    <div class="sectionL3">

    <h3>Mapper Extensions must return EXT_CONTINUE to continue execution to the next mapper</h3>
    
    

<p>If you extend the mapper, the methods in your mapper extension must return EXT_CONTINUE to continue executing additional mappers.
</p>




            <a href="#top" class="totoc">back to section top</a>
    </div>




    </div>




    </div>





    <div class="bottomnav">
        
    <div class="prevnext">


            
            Next: <a href="ormtutorial.html">Object Relational Tutorial</a>
    </div>

    </div>






</body>
</html>






